home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / docs / libgpp / iostream.i2 < prev    next >
Encoding:
GNU Info File  |  1994-12-18  |  18.2 KB  |  430 lines
  1. This is Info file iostream.info, produced by Makeinfo-1.55 from the
  2. input file ./iostream.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * iostream: (iostream).                    The C++ input/output facility.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file describes libio, the GNU library for C++ iostreams and C
  9. stdio.
  10.  
  11.    libio includes software developed by the University of California,
  12. Berkeley.
  13.  
  14.    Copyright (C) 1993 Free Software Foundation, Inc.
  15.  
  16.    Permission is granted to make and distribute verbatim copies of this
  17. manual provided the copyright notice and this permission notice are
  18. preserved on all copies.
  19.  
  20.    Permission is granted to copy and distribute modified versions of
  21. this manual under the conditions for verbatim copying, provided also
  22. that the entire resulting derived work is distributed under the terms
  23. of a permission notice identical to this one.
  24.  
  25.    Permission is granted to copy and distribute translations of this
  26. manual into another language, under the above conditions for modified
  27. versions.
  28.  
  29. 
  30. File: iostream.info,  Node: Formatting,  Next: Stdiobuf,  Prev: Overflow,  Up: Streambuf
  31.  
  32. C-style formatting for `streambuf' objects
  33. ==========================================
  34.  
  35.    The GNU `streambuf' class supports `printf'-like formatting and
  36. scanning.
  37.  
  38.  - Method: int streambuf::vform (const char *FORMAT, ...)
  39.      Similar to `fprintf(FILE, FORMAT, ...)'.  The FORMAT is a
  40.      `printf'-style format control string, which is used to format the
  41.      (variable number of) arguments, printing the result on the `this'
  42.      streambuf.  The result is the number of characters printed.
  43.  
  44.  - Method: int streambuf::vform (const char *FORMAT, va_list ARGS)
  45.      Similar to `vfprintf(FILE, FORMAT, ARGS)'.  The FORMAT is a
  46.      `printf'-style format control string, which is used to format the
  47.      argument list ARGS, printing the result on the `this' streambuf.
  48.      The result is the number of characters printed.
  49.  
  50.  - Method: int streambuf::scan (const char *FORMAT, ...)
  51.      Similar to `fscanf(FILE, FORMAT, ...)'.  The FORMAT is a
  52.      `scanf'-style format control string, which is used to read the
  53.      (variable number of) arguments from the `this' streambuf.  The
  54.      result is the number of items assigned, or `EOF' in case of input
  55.      failure before any conversion.
  56.  
  57.  - Method: int streambuf::vscan (const char *FORMAT, va_list ARGS)
  58.      Like `streambuf::scan', but takes a single `va_list' argument.
  59.  
  60. 
  61. File: iostream.info,  Node: Stdiobuf,  Next: Procbuf,  Prev: Formatting,  Up: Streambuf
  62.  
  63. Wrappers for C `stdio'
  64. ======================
  65.  
  66.    A "stdiobuf" is a `streambuf' object that points to a `FILE' object
  67. (as defined by `stdio.h').  All `streambuf' operations on the
  68. `stdiobuf' are forwarded to the `FILE'.  Thus the `stdiobuf' object
  69. provides a wrapper around a `FILE', allowing use of `streambuf'
  70. operations on a `FILE'.  This can be useful when mixing C code with C++
  71. code.
  72.  
  73.    The pre-defined streams `cin', `cout', and `cerr' are normally
  74. implemented as `stdiobuf' objects that point to respectively `stdin',
  75. `stdout', and `stderr'.  This is convenient, but it does cost some
  76. extra overhead.
  77.  
  78.    If you set things up to use the implementation of `stdio' provided
  79. with this library, then `cin', `cout', and `cerr' will be set up to to
  80. use `stdiobuf' objects, since you get their benefits for free.  *Note C
  81. Input and Output: Stdio.
  82.  
  83. 
  84. File: iostream.info,  Node: Procbuf,  Next: Backing Up,  Prev: Stdiobuf,  Up: Streambuf
  85.  
  86. Reading/writing from/to a pipe
  87. ==============================
  88.  
  89.    The "procbuf" class is a GNU extension.  It is derived from
  90. `streambuf'.  A `procbuf' can be "closed" (in which case it does
  91. nothing), or "open" (in which case it allows communicating through a
  92. pipe with some other program).
  93.  
  94.  - Constructor:  procbuf::procbuf ()
  95.      Creates a `procbuf' in a "closed" state.
  96.  
  97.  - Method: procbuf* procbuf::open (const char *COMMAND, int MODE)
  98.      Uses the shell (`/bin/sh') to run a program specified by COMMAND.
  99.  
  100.      If MODE is `ios::in', standard output from the program is sent to
  101.      a pipe; you can read from the pipe by reading from the `procbuf'.
  102.      (This is similar to `popen(COMMAND, "r")'.)
  103.  
  104.      If MODE is `ios::out', output written written to the `procbuf' is
  105.      written to a pipe; the program is set up to read its standard
  106.      input from (the other end of) the pipe.  (This is similar to
  107.      `popen(COMMAND, "w")'.)
  108.  
  109.      The `procbuf' must start out in the "closed" state.  Returns
  110.      `*this' on success, and `NULL' on failure.
  111.  
  112.  - Constructor:  procbuf::procbuf (const char *COMMAND, int MODE)
  113.      Calls `procbuf::open (COMMAND, MODE)'.
  114.  
  115.  - Method: procbuf* procbuf::close ()
  116.      Waits for the program to finish executing, and then cleans up the
  117.      resources used.  Returns `*this' on success, and `NULL' on failure.
  118.  
  119.  - Destructor:  procbuf::~procbuf ()
  120.      Calls `procbuf::close'.
  121.  
  122. 
  123. File: iostream.info,  Node: Backing Up,  Next: Indirectbuf,  Prev: Procbuf,  Up: Streambuf
  124.  
  125. Backing up
  126. ==========
  127.  
  128.    The GNU iostream library allows you to ask a `streambuf' to remember
  129. the current position.  This allows you to go back to this position
  130. later, after reading further.  You can back up arbitrary amounts, even
  131. on unbuffered files or multiple buffers' worth, as long as you tell the
  132. library in advance.  This unbounded backup is very useful for scanning
  133. and parsing applications.  This example shows a typical scenario:
  134.  
  135.      // Read either "dog", "hound", or "hounddog".
  136.      // If "dog" is found, return 1.
  137.      // If "hound" is found, return 2.
  138.      // If "hounddog" is found, return 3.
  139.      // If none of these are found, return -1.
  140.      int my_scan(streambuf* sb)
  141.      {
  142.          streammarker fence(sb);
  143.          char buffer[20];
  144.          // Try reading "hounddog":
  145.          if (sb->sgetn(buffer, 8) == 8
  146.              && strncmp(buffer, "hounddog", 8) == 0)
  147.            return 3;
  148.          // No, no "hounddog":  Back up to 'fence'
  149.          sb->seekmark(fence); //
  150.          // ... and try reading "dog":
  151.          if (sb->sgetn(buffer, 3) == 3
  152.              && strncmp(buffer, "dog", 3) == 0)
  153.            return 1;
  154.          // No, no "dog" either:  Back up to 'fence'
  155.          sb->seekmark(fence); //
  156.          // ... and try reading "hound":
  157.          if (sb->sgetn(buffer, 5) == 5
  158.              && strncmp(buffer, "hound", 5) == 0)
  159.            return 2;
  160.          // No, no "hound" either:  Back up and signal failure.
  161.          sb->seekmark(fence); // Backup to 'fence'
  162.          return -1;
  163.      }
  164.  
  165.  - Constructor:  streammarker::streammarker (streambuf* SBUF)
  166.      Create a `streammarker' associated with SBUF that remembers the
  167.      current position of the get pointer.
  168.  
  169.  - Method: int streammarker::delta (streammarker& MARK2)
  170.      Return the difference between the get positions corresponding to
  171.      `*this' and MARK2 (which must point into the same `streambuffer'
  172.      as `this').
  173.  
  174.  - Method: int streammarker::delta ()
  175.      Return the position relative to the streambuffer's current get
  176.      position.
  177.  
  178.  - Method: int streambuf::seekmark (streammarker& MARK)
  179.      Move the get pointer to where it (logically) was when MARK was
  180.      constructed.
  181.  
  182. 
  183. File: iostream.info,  Node: Indirectbuf,  Prev: Backing Up,  Up: Streambuf
  184.  
  185. Forwarding I/O activity
  186. =======================
  187.  
  188.    An "indirectbuf" is one that forwards all of its I/O requests to
  189. another streambuf.
  190.  
  191.    An `indirectbuf' can be used to implement Common Lisp
  192. synonym-streams and two-way-streams:
  193.  
  194.      class synonymbuf : public indirectbuf {
  195.         Symbol *sym;
  196.         synonymbuf(Symbol *s) { sym = s; }
  197.         virtual streambuf *lookup_stream(int mode) {
  198.             return coerce_to_streambuf(lookup_value(sym)); }
  199.      };
  200.  
  201. 
  202. File: iostream.info,  Node: Stdio,  Next: Index,  Prev: Streambuf,  Up: Top
  203.  
  204. C Input and Output
  205. ******************
  206.  
  207.    `libio' is distributed with a complete implementation of the ANSI C
  208. `stdio' facility.  It is implemented using `streambuf' objects.  *Note
  209. Wrappers for C `stdio': Stdiobuf.
  210.  
  211.    The `stdio' package is intended as a replacement for the whatever
  212. `stdio' is in your C library.  Since `stdio' works best when you build
  213. `libc' to contain it, and that may be inconvenient, it is not installed
  214. by default.
  215.  
  216.    Extensions beyond ANSI:
  217.  
  218.    * A stdio `FILE' is identical to a streambuf.  Hence there is no
  219.      need to worry about synchronizing C and C++ input/output--they are
  220.      by definition always synchronized.
  221.  
  222.    * If you create a new streambuf sub-class (in C++), you can use it
  223.      as a `FILE' from C.  Thus the system is extensible using the
  224.      standard `streambuf' protocol.
  225.  
  226.    * You can arbitrarily mix reading and writing, without having to seek
  227.      in between.
  228.  
  229.    * Unbounded `ungetc()' buffer.
  230.  
  231. 
  232. File: iostream.info,  Node: Index,  Prev: Stdio,  Up: Top
  233.  
  234. Index
  235. *****
  236.  
  237. * Menu:
  238.  
  239. * (:                                    States.
  240. * (:                                    States.
  241. * << on ostream:                        Operators.
  242. * >> on istream:                        Operators.
  243. * iostream destructor:                  Iostream.
  244. * badbit:                               States.
  245. * beg:                                  Output Position.
  246. * cerr:                                 Operators.
  247. * cin:                                  Operators.
  248. * class fstreambase:                    Files.
  249. * class fstream:                        Files.
  250. * class ifstream:                       Files.
  251. * class istrstream:                     Strings.
  252. * class ostream:                        Files.
  253. * class ostrstream:                     Strings.
  254. * class strstreambase:                  Strings.
  255. * class strstreambuf:                   Strings.
  256. * class strstream:                      Strings.
  257. * cout:                                 Operators.
  258. * cur:                                  Output Position.
  259. * dec:                                  Manipulators.
  260. * destructor for iostream:              Iostream.
  261. * end:                                  Output Position.
  262. * endl:                                 Manipulators.
  263. * ends:                                 Manipulators.
  264. * eofbit:                               States.
  265. * failbit:                              States.
  266. * flush:                                Ostream Housekeeping.
  267. * flush:                                Manipulators.
  268. * fstream:                              Files.
  269. * fstreambase:                          Files.
  270. * fstreambase::close:                   Files.
  271. * get area:                             Areas.
  272. * goodbit:                              States.
  273. * hex:                                  Manipulators.
  274. * ifstream:                             Files and Strings.
  275. * ifstream:                             Files.
  276. * ifstream::ifstream:                   Files.
  277. * ifstream::ifstream:                   Files.
  278. * ifstream::ifstream:                   Files.
  279. * ifstream::open:                       Files.
  280. * ios::app:                             Files.
  281. * ios::ate:                             Files.
  282. * ios::bad:                             States.
  283. * ios::beg:                             Input Position.
  284. * ios::bin:                             Files.
  285. * ios::bitalloc:                        Extending.
  286. * ios::clear:                           States.
  287. * ios::cur:                             Input Position.
  288. * ios::dec:                             Format Control.
  289. * ios::end:                             Input Position.
  290. * ios::eof:                             States.
  291. * ios::fail:                            States.
  292. * ios::fill:                            Format Control.
  293. * ios::fill:                            Format Control.
  294. * ios::fixed:                           Format Control.
  295. * ios::flags:                           Format Control.
  296. * ios::flags:                           Format Control.
  297. * ios::good:                            States.
  298. * ios::hex:                             Format Control.
  299. * ios::in:                              Files.
  300. * ios::internal:                        Format Control.
  301. * ios::ios:                             Ios.
  302. * ios::iword:                           Extending.
  303. * ios::iword:                           Extending.
  304. * ios::left:                            Format Control.
  305. * ios::nocreate:                        Files.
  306. * ios::noreplace:                       Files.
  307. * ios::oct:                             Format Control.
  308. * ios::out:                             Files.
  309. * ios::precision:                       Format Control.
  310. * ios::precision:                       Format Control.
  311. * ios::pword:                           Extending.
  312. * ios::pword:                           Extending.
  313. * ios::rdbuf:                           Streambuf from Ios.
  314. * ios::rdstate:                         States.
  315. * ios::right:                           Format Control.
  316. * ios::scientific:                      Format Control.
  317. * ios::seekdir:                         Output Position.
  318. * ios::set:                             States.
  319. * ios::setf:                            Format Control.
  320. * ios::setf:                            Format Control.
  321. * ios::setstate:                        States.
  322. * ios::showbase:                        Format Control.
  323. * ios::showpoint:                       Format Control.
  324. * ios::showpos:                         Format Control.
  325. * ios::skipws:                          Format Control.
  326. * ios::stdio:                           Format Control.
  327. * ios::sync_with_stdio:                 Synchronization.
  328. * ios::tie:                             Synchronization.
  329. * ios::tie:                             Synchronization.
  330. * ios::trunc:                           Files.
  331. * ios::unitbuf:                         Format Control.
  332. * ios::unsetf:                          Format Control.
  333. * ios::uppercase:                       Format Control.
  334. * ios::width:                           Format Control.
  335. * ios::width:                           Format Control.
  336. * ios::xalloc:                          Extending.
  337. * ios::~ios:                            Ios.
  338. * iostream::iostream:                   Iostream.
  339. * iostream::iostream:                   Iostream.
  340. * istream::gcount:                      Istream Housekeeping.
  341. * istream::get:                         Char Input.
  342. * istream::get:                         Char Input.
  343. * istream::get:                         String Input.
  344. * istream::get:                         String Input.
  345. * istream::getline:                     String Input.
  346. * istream::gets:                        String Input.
  347. * istream::ignore:                      Istream Housekeeping.
  348. * istream::ipfx:                        Istream Housekeeping.
  349. * istream::isfx:                        Istream Housekeeping.
  350. * istream::istream:                     Istream.
  351. * istream::istream:                     Istream.
  352. * istream::peek:                        Char Input.
  353. * istream::putback:                     Istream Housekeeping.
  354. * istream::read:                        String Input.
  355. * istream::scan:                        String Input.
  356. * istream::seekg:                       Input Position.
  357. * istream::seekg:                       Input Position.
  358. * istream::tellg:                       Input Position.
  359. * istream::unget:                       Istream Housekeeping.
  360. * istream::vscan:                       String Input.
  361. * istrstream:                           Strings.
  362. * istrstream:                           Files and Strings.
  363. * istrstream::istrstream:               Strings.
  364. * oct:                                  Manipulators.
  365. * ofstream:                             Files and Strings.
  366. * ofstream::ofstream:                   Files.
  367. * ofstream::ofstream:                   Files.
  368. * ofstream::ofstream:                   Files.
  369. * ofstream::open:                       Files.
  370. * ofstream::~ofstream:                  Files.
  371. * ostream:                              Files.
  372. * ostream::form:                        Writing.
  373. * ostream::opfx:                        Ostream Housekeeping.
  374. * ostream::osfx:                        Ostream Housekeeping.
  375. * ostream::ostream:                     Ostream.
  376. * ostream::ostream:                     Ostream.
  377. * ostream::put:                         Writing.
  378. * ostream::seekp:                       Output Position.
  379. * ostream::seekp:                       Output Position.
  380. * ostream::tellp:                       Output Position.
  381. * ostream::vform:                       Writing.
  382. * ostream::write:                       Writing.
  383. * ostrstream:                           Strings.
  384. * ostrstream:                           Files and Strings.
  385. * ostrstream::freeze:                   Strings.
  386. * ostrstream::frozen:                   Strings.
  387. * ostrstream::ostrstream:               Strings.
  388. * ostrstream::ostrstream:               Strings.
  389. * ostrstream::pcount:                   Strings.
  390. * ostrstream::str:                      Strings.
  391. * procbuf::close:                       Procbuf.
  392. * procbuf::open:                        Procbuf.
  393. * procbuf::procbuf:                     Procbuf.
  394. * procbuf::procbuf:                     Procbuf.
  395. * procbuf::~procbuf:                    Procbuf.
  396. * put area:                             Areas.
  397. * setbase:                              Manipulators.
  398. * setfill:                              Manipulators.
  399. * setprecision:                         Format Control.
  400. * setprecision:                         Manipulators.
  401. * setting ios::precision:               Format Control.
  402. * setting ios::width:                   Format Control.
  403. * setw:                                 Format Control.
  404. * setw:                                 Manipulators.
  405. * streambuf::eback:                     Areas.
  406. * streambuf::egptr:                     Areas.
  407. * streambuf::epptr:                     Areas.
  408. * streambuf::gptr:                      Areas.
  409. * streambuf::pbase:                     Areas.
  410. * streambuf::pbump:                     Areas.
  411. * streambuf::pptr:                      Areas.
  412. * streambuf::scan:                      Formatting.
  413. * streambuf::seekmark:                  Backing Up.
  414. * streambuf::setg:                      Areas.
  415. * streambuf::setp:                      Areas.
  416. * streambuf::vform:                     Formatting.
  417. * streambuf::vform:                     Formatting.
  418. * streambuf::vscan:                     Formatting.
  419. * streambuf:gbump:                      Areas.
  420. * streammarker::delta:                  Backing Up.
  421. * streammarker::delta:                  Backing Up.
  422. * streammarker::streammarker:           Backing Up.
  423. * strstream:                            Strings.
  424. * strstreambase:                        Strings.
  425. * strstreambase::rdbuf:                 Strings.
  426. * strstreambuf:                         Strings.
  427. * ws:                                   Manipulators.
  428.  
  429.  
  430.